

ixgbevf Linux* Virtual Function (VF) Driver for Intel Ethernet Network Connection
=================================================================


================================================================================

November 24, 2014

================================================================================


Contents
--------

- Overview
- Building and Installation
- Command Line Parameters
- Additional Configurations
- Known Issues
- Support
- License

================================================================================


Overview
--------


The ixgbevf driver supports 82599, X540, X550, and X552-based virtual
function devices that can only be activated on kernels that support SR-IOV.
SR-IOV requires the correct platform and OS support.

This file describes the ixgbevf Linux* Virtual Function Driver for the 
10 Gigabit PCI Express Family of Adapters. The driver supports kernel versions 
2.6.x and 3.x.

The ixgbevf driver requires the ixgbe driver, version 2.0 or later. The
ixgbevf driver supports virtual functions generated by the ixgbe driver with a
max_vfs value of 1 or greater. For more information on the max_vfs parameter
refer to the section section of the ixgbe driver.

The guest OS loading the ixgbevf driver must support MSI-X interrupts.

This driver is only supported as a loadable module at this time. Intel is not
supplying patches against the kernel source to allow for static linking of the
driver. For questions related to hardware requirements, refer to the
documentation supplied with your Intel Gigabit adapter. All hardware
requirements listed apply to use with Linux.

Instructions on updating ethtool can be found in the section "Additional
Configurations" later in this document.

VLANs: There is a limit of a total of 64 shared VLANs to 1 or more VFs.


Identifying Your Adapter
------------------------

For more information on how to identify your adapter, go to the Adapter &
Driver ID Guide at:
http://support.intel.com/support/go/network/adapter/proidguide.htm

For the latest Intel network drivers for Linux, refer to the following
website. Select the link for your adapter.
http://support.intel.com/support/go/network/adapter/home.htm
================================================================================


Building and Installation
-------------------------


To build a binary RPM* package of this driver, run 'rpmbuild -tb
<filename.tar.gz>'. Replace <filename.tar.gz> with the specific filename of
the driver.

NOTES:

- For the build to work properly, the currently running kernel MUST match
  the version and configuration of the installed kernel sources. If you have
  just recompiled the kernel reboot the system now.
- RPM functionality has only been tested in Red Hat distributions.

1. Move the virtual function driver tar file to the directory of your 
   choice. For example, use '/home/username/ixgbevf' or 
   '/usr/local/src/ixgbevf'.

2. Untar/unzip the archive, where <x.x.x> is the version number for the
   driver tar file:
   tar zxf ixgbevf-<x.x.x>.tar.gz
3. Change to the driver src directory, where <x.x.x> is the version number
   for the driver tar:
   cd ixgbevf-<x.x.x>/src/
4. Compile the driver module:
   # make install

   The binary will be installed as:
   /lib/modules/<KERNEL VERSION>/kernel/drivers/net/ixgbevf/ixgbevf.[k]o

   The install location listed above is the default location. This may differ
   for various Linux distributions.

5. Load the module using the modprobe command:
   modprobe ixgbevf

   With 2.6 based kernels also make sure that older ixgbevf drivers are
   removed from the kernel, before loading the new module:
   rmmod ixgbevf; modprobe ixgbevf
6. Assign an IP address to the interface by entering the following, where x
   is the interface number:
   ifconfig eth <x> <IP_address>
7. Verify that the interface works. Enter the following, where IP_address
   is the IP address for another machine on the same subnet as the interface
   that is being tested:
   ping <IP_address>

================================================================================


Command Line Parameters
-----------------------


If the driver is built as a module, the following optional parameters are used
by entering them on the command line with the modprobe command using this
syntax:
modprobe ixgbevf [<option>=<VAL1>,<VAL2>,...]

There needs to be a <VAL#> for each network port in the system supported by
this driver. The values will be applied to each instance, in function order.
For example:
modprobe ixgbevf InterruptThrottleRate=16000,16000

In this case, there are two network ports supported by ixgbevf in the system.
The default value for each parameter is generally the recommended setting,
unless otherwise noted.

NOTES:

- For more information about the AutoNeg, Duplex, and Speed parameters, see
  the "Speed and Duplex Configuration" section in this document.
- For more information about the InterruptThrottleRate parameter, see the
  application note at: http://www.intel.com/design/network/applnots/ap450.htm
- A descriptor describes a data buffer and attributes related to the data
  buffer. This information is accessed by the hardware.


InterruptThrottleRate
---------------------


Valid Range:  0, 1, 956-488281 (0=off, 1=dynamic)

Default Value:  1

The InterruptThrottleRate (ITR) parameter controls how many interrupts each 
vector can generate per second. Increasing ITR lowers latency at the cost of 
increased CPU utilization. Although, increasing ITR may help throughput 
in some circumstances.

The driver has an adaptive mode (setting 1) in which it dynamically adjusts
the InterruptThrottleRate based on receive traffic. After determining the 
incoming traffic in the last timeframe, it adjusts the InterruptThrottleRate 
to suit that traffic type the best. There are three classes defined:

- Bulk traffic. Large amounts of packets of a normal size.

- Low latency. Small amounts of traffic and/or significant percentage of
  small packets.

- Lowest latency. Almost completely small packets or minimal traffic.

Setting InterruptThrottleRate to 0 turns off any interrupt moderation and may
improve small packet latency, but it is generally not suitable for bulk 
throughput traffic.


================================================================================


Additional Configurations
-------------------------



Configuring the Driver on Different Distributions
-------------------------------------------------


Configuring a network driver to load properly when the system is started is
distribution dependent. Typically, the configuration process involves adding
an alias line to /etc/modules.conf or /etc/modprobe.conf as well as editing
other system startup scripts and/or configuration files. Many popular Linux
distributions ship with tools to make these changes for you. To learn the
proper way to configure a network device for your system, refer to your
distribution documentation. If during this process you are asked for the
driver or module name, the name for the Linux Virtual Functioin Driver for 
the Gigabit Family of Adapters is ixgbevf.

As an example, if you install the ixgbevf driver for two adapters (eth0 and
eth1) and want to set the interrupt mode to MSI-X and MSI respectively, add
the following to modules.conf or /etc/modprobe.conf:
alias eth0 ixgbevf
alias eth1 ixgbevf
options ixgbevf InterruptThrottleRate=3,1

Viewing Link Messages
---------------------


Link messages will not be displayed to the console if the distribution is
restricting system messages. In order to see network driver link messages on
your console, set dmesg to eight by entering the following: dmesg -n 8

NOTES: This setting is not saved across reboots.


ethtool
-------


The driver utilizes the ethtool interface for driver configuration and
diagnostics, as well as displaying statistical information. ethtool version 3
or later is required for this functionality, although we strongly recommend
downloading the latest version at:
http://ftp.kernel.org/pub/software/network/ethtool/.

MACVLAN
-------


ixgbevf supports MACVLAN on kernels that have the feature included. Kernel
support for MACVLAN can be tested by checking if the MACVLAN driver is loaded.
The user can run 'lsmod | grep macvlan' to see if the MACVLAN driver is loaded
or run 'modprobe macvlan' to try to load the MACVLAN driver.

It may be necessary to update to a recent release of the iproute2 package to
get support of MACVLAN via the 'ip' command.


NAPI
----


NAPI (Rx polling mode) is supported in the ixgbevf driver and is always
enabled. For more information on NAPI, go to:
ftp://robur.slu.se/pub/Linux/net-development/NAPI/usenix-paper.tgz
================================================================================


Known Issues/Troubleshooting
----------------------------



Hardware Issues
---------------


For known hardware and troubleshooting issues, either refer to the "Release
Notes" in your User Guide, or for more detailed information, go to
http://www.intel.com.

In the search box enter your devices controller ID followed by "spec update"
(i.e., 82599 spec update). The specification update file has complete
information on known hardware issues.


Software Issues
---------------


NOTE: After installing the driver, if your Intel Ethernet Network Connection
is not working, verify that you have installed the correct driver.


Compiling the Driver
--------------------


When trying to compile the driver by running make install, the following error
may occur:  "Linux kernel source not configured - missing version.h"

To solve this issue, create the version.h file by going to the Linux source
tree and entering:
# make include/linux/version.h

Multiple Interfaces on Same Ethernet Broadcast Network
------------------------------------------------------


Due to the default ARP behavior on Linux, it is not possible to have one
system on two IP networks in the same Ethernet broadcast domain
(non-partitioned switch) behave as expected. All Ethernet interfaces will
respond to IP traffic for any IP address assigned to the system. This results
in unbalanced receive traffic.

If you have multiple interfaces in a server, either turn on ARP filtering by
entering: echo 1 > /proc/sys/net/ipv4/conf/all/arp_filter

This only works if your kernel's version is higher than 2.4.5.

NOTE: This setting is not saved across reboots. The configuration change can
be made permanent by adding the following line to the /etc/sysctl.conf file:
net.ipv4.conf.all.arp_filter = 1

or,
install the interfaces in separate broadcast domains (either in different
switches or in a switch partitioned to VLANs)

Build Error with Asianux 3.0 - Redefinition of typedef 'irq_handler_t'
----------------------------------------------------------------------


Some systems may experience build issues due to the redefinition of
irq_handler_t. To resolve this issue, build the driver (step 4 above) using
the command:
# make CFLAGS_EXTRA=-DAX_RELEASE_CODE=1 install

MSI-X Issues with Kernels between 2.6.19 and 2.6.21 (inclusive)
---------------------------------------------------------------


Kernel panics and instability may be observed on any MSI-X hardware if you use
irqbalance with kernels between 2.6.19 and 2.6.21. If such problems are
encountered, you may disable the irqbalance daemon or upgrade to a newer
kernel.


Rx Page Allocation Errors
-------------------------


"order:0" errors may occur under stress with kernels 2.6.25 and newer. This is
caused by the way the Linux kernel reports this stressed condition.


Host May Reboot after Removing PF when VF is Active in Guest
------------------------------------------------------------


Using kernel versions earlier than 3.2, do not unload the PF driver with
active VFs. Doing this will cause your VFs to stop working until you reload
the PF driver and may cause a spontaneous reboot of your system.

================================================================================


Support
-------


For general information, go to the Intel support website at:
www.intel.com/support/

or the Intel Wired Networking project hosted by Sourceforge at:
http://sourceforge.net/projects/e1000

If an issue is identified with the released source code on the supported
kernel with a supported adapter, email the specific information related to the
issue to e1000-devel@lists.sf.net.

================================================================================


License
-------


Intel 10 Gigabit Linux driver.
Copyright(c) 1999 - 2014 Intel Corporation.

This program is free software; you can redistribute it and/or modify it under
the terms and conditions of the GNU General Public License, version 2, as
published by the Free Software Foundation.

This program is distributed in the hope it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
St - Fifth Floor, Boston, MA 02110-1301 USA.

The full GNU General Public License is included in this distribution in the
file called "COPYING".

================================================================================


Trademarks
----------


Intel, Itanium, and Pentium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.

